home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Special 24 / AMIGAplus Sonderheft 24 (2000)(Falke)(DE)[!].iso / PublicDomain / Anwendungen / MCControl / Modules / Modules.doc < prev    next >
Text File  |  2000-01-01  |  13KB  |  338 lines
  1. ;----------------------------------------------------------------------------
  2. ; $VER: MCControlModule.Doc 1.40 (19.02.2000)
  3. ;----------------------------------------------------------------------------
  4. ;This is not an documentation how to use the .mcm modules in your own
  5. ;software! Its an documentation about how to write modules for other
  6. ;card reader.
  7. ;----------------------------------------------------------------------------
  8. TABLE OF CONTENTS
  9.  
  10. MCControlModule/General
  11. MCControlModule/Module_Info
  12. MCControlModule/Module_Open
  13. MCControlModule/Module_Close
  14. MCControlModule/Module_AccessDirectFrame
  15. MCControlModule/Module_AccessDirectPage
  16. MCControlModule/Module_AccessRawFrame
  17. MCControlModule/Module_AccessRawPage
  18. ;----------------------------------------------------------------------------
  19.  
  20. First the main structure:
  21.  
  22. Module_Identifier       = "MCCM"
  23. Module_VersionNumber    = 1
  24.         RSRESET
  25. Module_Code                 rs.w 1 ;MUST $4e75 (RTS)
  26. Module_Version              rs.w 1 ;Must be Module_VersionNumber
  27. Module_ID                   rs.l 1 ;Must be "MCCM"
  28. Module_Flags                rs.l 1 ;see below (unused flags must be zero)
  29. Module_Exec_Base            rs.l 1 ;Filled by MCControl
  30. Module_Dos_Base             rs.l 1 ;Filled by MCControl
  31. Module_Intuition_Base       rs.l 1 ;Filled by MCControl
  32. ;--- Card Data
  33. Module_Reserved1            rs.l 14 ;Reserved (must be ZERO)
  34. ;--- Jump Table
  35. Module_Info                 rs.w 3
  36. Module_Open                 rs.w 3
  37. Module_Close                rs.w 3
  38. Module_ReservedFunctions2   rs.w 3*7 ;Reserved
  39. Module_AccessDirectFrame    rs.w 3
  40. Module_AccessDirectPage     rs.w 3
  41. Module_AccessRawFrame       rs.w 3
  42. Module_AccessRawPage        rs.w 3
  43. Module_ReservedFunctions3   rs.w 3*6 ;reserved
  44. Module_SIZEOF               rs.b 0
  45. ;----------------------------------------------------------------------------
  46. ;--- Enable transfer routines:
  47.  BITDEF Module,AccessDirectFrame,3  ;Driver supports DirectFrameAccess
  48.  BITDEF Module,AccessDirectPage,7   ;Driver supports DirectPageAccess
  49.  BITDEF Module,AccessRawFrame,6     ;Driver supports RawFrameAccess
  50.  BITDEF Module,AccessRawPage,8      ;Driver supports RawPageAccess
  51. ;--- Enable gadgets within the settings window:
  52.  BITDEF Module,ConfigMultiPage,5    ;Driver requires MultiPage setup
  53.  BITDEF Module,Reserved2,0          ;Must be Zero
  54.  BITDEF Module,ConfigDevice,1       ;Driver requires an Device/Unit selector
  55. ;--- Enable special functions:
  56.  BITDEF Module,EnableMultiPage,2    ;Turn on MultiPage support
  57.  BITDEF Module,EnableMultiSlot,4    ;Turn on MultiSlot support
  58.  BITDEF Module,EnableModuleInfo,9   ;Turn on ModuleInfo support
  59. ;----------------------------------------------------------------------------
  60. Module_Error_NoError       = 0
  61. Module_Error_OpenDevice    = 1 ;Opening the given device fails!
  62. Module_Error_NotCompatible = 2 ;If hardware supports identification!
  63. Module_Error_NoTimerDevice = 3 ;If you need the timer.device and opening fails
  64. Module_Error_NoParallelPort= 4 ;No ParallelPort resource
  65. Module_Error_NoResources   = 5 ;Use for missing signals, CIA Interrupts,...
  66. Module_Error_OutOfMemory   = 20
  67. ;----------------------------------------------------------------------------
  68. ;--- For AccessDirectFrame (Mode)
  69. Module_AccessDirect_Read    = 0
  70. Module_AccessDirect_Write   = 1
  71. ;--- For AccessDirectPage (Mode)
  72. Module_AccessDirect_Up      = 0
  73. Module_AccessDirect_Down    = 1
  74. ;----------------------------------------------------------------------------
  75. ;----------------------------------------------------------------------------
  76.  
  77.  NOTES 
  78.  
  79.    The exec, dos and intuition  bases  are  for  free  usage.  This  saves
  80.    memory,  time and of cource code size. The card data is for free usage,
  81.    too.
  82.  
  83.    Beside the arguments delivered for  each  function  you´ll  receive  an
  84.    pointer on the module itself in register A4!
  85.  
  86.    Make sure to backup a2-a5 and d2-d7 just like the Amiga-OS is doing!
  87.  
  88.    You must implement port and device allocation! Don´t try to  play  with
  89.    the  hardware without owning the right to do so. If possible try to use
  90.    parallel.device or serial.device. (The  user  defined  device  will  be
  91.    given during Module_Open().
  92.        
  93.    It´s not required to create an real  jumptable,  by  using  JMPs.  Feel
  94.    free, to use an BRA followed by an NOP. (See RamCard.mcm)
  95.        
  96.    Implement the code as fast as possible, because its used for many times
  97.    during reading and writing memory cards. Try to avoid overhead by using
  98.    Module_Open.
  99.  
  100.    If you need help then ask me and I´am telling you what to  do.  If  you
  101.    don´t  know how to code a driver then send me your information and I´ll
  102.    do my very best.
  103.  
  104. ;----------------------------------------------------------------------------
  105. ;----------------------------------------------------------------------------
  106. MCControlModule/Module_Info
  107.  
  108.    NAME
  109.                  Module_Info -- open and inits the module
  110.  
  111.    SYNOPSIS
  112.                  Error   = Module_Info(Buffer, BufferSize)
  113.                  D0                    a0,     d0
  114.  
  115.                  (ULONG) = Module_Open(*UBYTE, ULONG)
  116.  
  117.    FUNCTION
  118.                  Give MCControl special information about your driver,
  119.                  the hardware version detected or something like that.
  120.  
  121.    INPUTS
  122.                  Buffer:     Destination buffer for your message
  123.                  BufferSize: Size of the destinaton buffer! Make sure you
  124.                              don´t write more than these numbe of bytes!
  125.  
  126.    RESULT
  127.                   0 = No Error
  128.  
  129.                  Other results are currently not allowed!!
  130.  
  131.    NOTES
  132.                  Please support this routine! Even if there isn´t any
  133.                  important to say, then just report the version strings
  134.                  like shown in the example sources.
  135.  
  136.                  Buffer is garanted to be 100 bytes at minimum. If you are
  137.                  not sure your routine may create longer strings, then use
  138.                  BufferSize to not step over boundaries. The visible gadget
  139.                  space isn´t very big, so take an eye on this, too!
  140.  
  141.                  This function requires the flag: ModuleF_EnableModuleInfo!
  142.                  Otherwise MCControl is ignoring this routine.
  143.  
  144.    SEE ALSO
  145.                  Module_Close()
  146. ;----------------------------------------------------------------------------
  147. MCControlModule/Module_Open
  148.  
  149.    NAME
  150.                  Module_Open -- open and inits the module
  151.  
  152.    SYNOPSIS
  153.                  Error   = Module_Open(Device, Unit)
  154.                  D0                    a0,     d0
  155.  
  156.                  (ULONG) = Module_Open(*UBYTE,ULONG)
  157.  
  158.    FUNCTION
  159.                  Open the required device and alloc additional memory
  160.                  if needed.
  161.  
  162.    INPUTS
  163.                  Device: Pointer on device name (STRING IS READ ONLY!!!)
  164.                  Unit:   Unit of the given device
  165.  
  166.    RESULT
  167.                   0 = No Error
  168.                   1 = Open device error
  169.                   2 = Not compatible
  170.                   3 = time.device open error
  171.                   4 = No parallel resource
  172.                   5 = No resources (no signals, CIA interrupts)
  173.                  20 = Out of memory
  174.  
  175.                  Other results are currently not allowed!!
  176.  
  177.    NOTES
  178.                  Device and Unit are only valid if the ModuleF_ConfigDevice
  179.                  flag within the module structure (Module_Flags) is set.
  180.  
  181.    SEE ALSO
  182.                  Module_Close()
  183. ;----------------------------------------------------------------------------
  184. MCControlModule/Module_Close
  185.  
  186.    NAME
  187.                  Module_Close -- free all data and close all devices.
  188.  
  189.    SYNOPSIS
  190.                  Module_Close()
  191.  
  192.    FUNCTION
  193.                  Close all devices and free all allocated memory .
  194.  
  195.    NOTES
  196.                  Module_Close must be save to be called more than
  197.                  one time. This means you must detect an closing of
  198.                  an just closed module. In this case you must return
  199.                  without any action.
  200.  
  201.    SEE ALSO
  202.                  Module_Open()
  203. ;----------------------------------------------------------------------------
  204. MCControlModule/Module_AccessDirectFrame
  205.  
  206.    NAME
  207.                  Module_AccessDirectFrame -- Handles a